ποΈGitΠ―ΡΠ°ποΈ
specs/005-tak-v2-protocol/data-model.md 988db081b289cbc23d9bceef8e7d85ab46d0e6a4 (988db081) Text, 9.77 KB
Data Model: TAK v2 Protocol Integration
Core Entities
CoTMessage (Central Domain Model)
The primary data model flowing between TAK clients, the TAK server, and the mesh network.
T282828
Tf0883e@Serializable
Tff7b72data Tff7b72class T56d364CoTMessageTb4b4b4(
Tff7b72val Te6edf3uidTb4b4b4: Tffa657StringTb4b4b4, T8b949e// Unique event ID (e.g., "ANDROID-device-uuid")
Tff7b72val Te6edf3typeTb4b4b4: Tffa657StringTb4b4b4, T8b949e// CoT type string (e.g., "a-f-G-U-C", "b-t-f")
Tff7b72val Te6edf3timeTb4b4b4: Te6edf3InstantTb4b4b4, T8b949e// Event creation time
Tff7b72val Te6edf3startTb4b4b4: Te6edf3InstantTb4b4b4, T8b949e// Event validity start
Tff7b72val Te6edf3staleTb4b4b4: Te6edf3InstantTb4b4b4, T8b949e// Event expiry time
Tff7b72val Te6edf3howTb4b4b4: Tffa657StringTb4b4b4, T8b949e// How generated (e.g., "m-g", "h-e")
Tff7b72val Te6edf3latitudeTb4b4b4: Tffa657DoubleTb4b4b4, T8b949e// WGS84 latitude
Tff7b72val Te6edf3longitudeTb4b4b4: Tffa657DoubleTb4b4b4, T8b949e// WGS84 longitude
Tff7b72val Te6edf3haeTb4b4b4: Tffa657DoubleTb4b4b4, T8b949e// Height above ellipsoid (meters)
Tff7b72val Te6edf3ceTb4b4b4: Tffa657DoubleTb4b4b4, T8b949e// Circular error (meters)
Tff7b72val Te6edf3leTb4b4b4: Tffa657DoubleTb4b4b4, T8b949e// Linear error (meters)
Tff7b72val Te6edf3contactTb4b4b4: Te6edf3CoTContact?Tb4b4b4, T8b949e// Contact info (callsign, endpoint)
Tff7b72val Te6edf3groupTb4b4b4: Te6edf3CoTGroup?Tb4b4b4, T8b949e// Team/role info
Tff7b72val Te6edf3statusTb4b4b4: Te6edf3CoTStatus?Tb4b4b4, T8b949e// Battery status
Tff7b72val Te6edf3trackTb4b4b4: Te6edf3CoTTrack?Tb4b4b4, T8b949e// Speed/course
Tff7b72val Te6edf3chatTb4b4b4: Te6edf3CoTChat?Tb4b4b4, T8b949e// Chat routing info
Tff7b72val Te6edf3remarksTb4b4b4: Tffa657String?Tb4b4b4, T8b949e// Free-text remarks
Tff7b72val Te6edf3rawDetailXmlTb4b4b4: Tffa657String?Tb4b4b4, T8b949e// Preserved inner <detail> XML for raw_detail
Tff7b72val Te6edf3parsedDetailXmlTb4b4b4: Te6edf3CoTDetailXml?Tb4b4b4, T8b949e// Parsed structured detail
Tff7b72val Te6edf3sourceEventXmlTb4b4b4: Tffa657String?Tb4b4b4, T8b949e// Full source XML for round-trip fidelity
Tb4b4b4)
Supporting Detail Models
T282828
Tf0883e@Serializable Tff7b72data Tff7b72class T56d364CoTContactTb4b4b4(Tff7b72val Te6edf3callsignTb4b4b4: Tffa657String?Tb4b4b4, Tff7b72val Te6edf3endpointTb4b4b4: Tffa657String?Tb4b4b4)
Tf0883e@Serializable Tff7b72data Tff7b72class T56d364CoTGroupTb4b4b4(Tff7b72val Te6edf3nameTb4b4b4: Tffa657String?Tb4b4b4, Tff7b72val Te6edf3roleTb4b4b4: Tffa657String?Tb4b4b4)
Tf0883e@Serializable Tff7b72data Tff7b72class T56d364CoTStatusTb4b4b4(Tff7b72val Te6edf3batteryTb4b4b4: Tffa657Int?Tb4b4b4)
Tf0883e@Serializable Tff7b72data Tff7b72class T56d364CoTTrackTb4b4b4(Tff7b72val Te6edf3speedTb4b4b4: Tffa657Double?Tb4b4b4, Tff7b72val Te6edf3courseTb4b4b4: Tffa657Double?Tb4b4b4)
Tf0883e@Serializable Tff7b72data Tff7b72class T56d364CoTChatTb4b4b4(Tff7b72val Te6edf3chatroomTb4b4b4: Tffa657String?Tb4b4b4, Tff7b72val Te6edf3idTb4b4b4: Tffa657String?Tb4b4b4, Tff7b72val Te6edf3senderCallsignTb4b4b4: Tffa657String?Tb4b4b4)
TAKClientInfo
Tracks connected TAK client state.
T282828
Tff7b72data Tff7b72class T56d364TAKClientInfoTb4b4b4(
Tff7b72val Te6edf3uidTb4b4b4: Tffa657String?Tb4b4b4, T8b949e// Client's self-reported UID
Tff7b72val Te6edf3callsignTb4b4b4: Tffa657String?Tb4b4b4, T8b949e// Client's callsign (from first PLI)
Tff7b72val Te6edf3connectionTimeTb4b4b4: Te6edf3InstantTb4b4b4, T8b949e// When client connected
Tb4b4b4)
InboundCoTMessage
Wraps a CoT message with its source client info for routing decisions.
T282828
Tff7b72data Tff7b72class T56d364InboundCoTMessageTb4b4b4(
Tff7b72val Te6edf3cotMessageTb4b4b4: Te6edf3CoTMessageTb4b4b4,
Tff7b72val Te6edf3clientInfoTb4b4b4: Te6edf3TAKClientInfo?Tb4b4b4, T8b949e// null if from mesh (not local TAK client)
Tb4b4b4)
Enum Mappings
CotType (23 mapped values + fallback)
βββββββββββββββββββββββββββββββ¬βββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β Enum Value β CoT String β Category β
βββββββββββββββββββββββββββββββΌβββββββββββββββββββββΌβββββββββββββββββββββββββββββ€
β CotTypePLIFriendly β "a-f-G-U-C" β Position (friendly ground) β
β CotTypePLIHostile β "a-h-G" β Position (hostile) β
β CotTypePLIUnknown β "a-u-G" β Position (unknown) β
β CotTypePLINeutral β "a-n-G" β Position (neutral) β
β CotTypeAircraftFriendly β "a-f-A" β Aircraft β
β CotTypeAircraftMilitary β "a-f-A-M" β Aircraft (military) β
β CotTypeAircraftHelicopter β "a-f-A-M-H" β Aircraft (helicopter) β
β CotTypeAircraftFixedWing β "a-f-A-C-F" β Aircraft (fixed wing) β
β CotType_GeoChat β "b-t-f" β Chat β
β CotType_DrawnShape β "u-d-f" β Drawing β
β CotType_Route β "b-m-r" β Route/Navigation β
β CotType_Marker β "b-m-p-s-p-i" β Marker (spot) β
β CotType_Waypoint β "b-m-p-s-p-loc" β Waypoint β
β CotType_Delete β "t-x-d-d" β Control β
β CotType_Casevac β "b-r-f-h-c" β Medical β
β CotType_Emergency β "b-a-o-pan" β Emergency β
β CotType_Alert β "b-a-o-opn" β Alert β
β CotType_Task β "b-i-v" β Tasking β
β ... (+ additional variants) β β β
β CotType_Other β (any unrecognized) β Fallback β
βββββββββββββββββββββββββββββββ΄βββββββββββββββββββββ΄βββββββββββββββββββββββββββββ
CotHow (4 mapped values)
βββββββββββββββββββββββ¬ββββββββββββββ¬ββββββββββββββββββββββββ
β Enum Value β String β Meaning β
βββββββββββββββββββββββΌββββββββββββββΌββββββββββββββββββββββββ€
β HOWHUMANENTERED β "h-e" β Human-entered β
β HOWMACHINEGENERATED β "m-g" β Machine-generated β
β HOWHUMANOSINT β "h-g-i-g-o" β Human-generated OSINT β
β HOWMACHINEREPORTED β "m-r" β Machine-reported β
βββββββββββββββββββββββ΄ββββββββββββββ΄ββββββββββββββββββββββββ
State Machines
TAK Server Lifecycle
T282828
ββββββββββββ
β STOPPED β
ββββββ¬ββββββ
β start()
βΌ
ββββββββββββ
β STARTING β (bind port 8089, load certs)
ββββββ¬ββββββ
β success
βΌ
ββββββββββββ accept() ββββββββββββββββββ
β RUNNING βββββββββββββββββββββββ CLIENT_CONNECTEDβ
β(0 clients)β β(n clients) β
ββββββ¬ββββββ βββββββββ¬ββββββββββ
β stop() β stop() / all disconnect
βΌ βΌ
ββββββββββββ
β STOPPED β
ββββββββββββ
TAK Client Connection Lifecycle
T282828
ββββββββββββββββ
β CONNECTED β (mTLS handshake complete)
ββββββββ¬ββββββββ
β first PLI received
βΌ
ββββββββββββββββ
β IDENTIFIED β (callsign + UID known)
ββββββββ¬ββββββββ
β socket error / timeout / client close
βΌ
ββββββββββββββββ
β DISCONNECTED β (scope cancelled, removed from list)
ββββββββββββββββ
Protocol Version Selection (per-send)
T282828
βββββββββββββββββββββββββββββββ
β CoT message from TAK client β
ββββββββββββββββ¬βββββββββββββββ
β
βββββββΌβββββββ
β useTakV2()?β
ββββ¬ββββββ¬ββββ
yes β β no
βΌ βΌ
βββββββββββββ βββββββββββββ
β V2 Path β β V1 Path β
β (port 78) β β (port 72) β
βββββββ¬ββββββ βββββββ¬ββββββ
β β
βββββββΌββββββ βββββββΌββββββ
βAll CoT β βPLI + Chat β
βtypes OK β βonly; else β
β β βdrop+warn β
βββββββ¬ββββββ βββββββ¬ββββββ
β β
βββββββΌββββββ βββββββΌββββββ
βCompress β βBare proto β
β(zstd+dict)β β(no compr.)β
βββββββ¬ββββββ βββββββ¬ββββββ
β β
βββββββΌββββββ βββββββΌββββββ
βCheck MTU β βSend on β
ββ€225 bytes β βport 72 β
βelse drop β βββββββββββββ
βββββββ¬ββββββ
β
βββββββΌββββββ
βSend on β
βport 78 β
βββββββββββββ
Validation Rules
βββββββββββββββββββββββββββββ¬βββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Rule β Error Handling β
βββββββββββββββββββββββββββββΌβββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Compressed payload size β β€ 225β¦ β Drop packet, log warning β
β Decompressed payload size β β€ MAXβ¦ β Reject packet (memory exhaustion prevention) β
β CoT XML structure β Validβ¦ β Parse returns T383838Result.failure β
β Latitude/Longitude β -90/9β¦ β Passed through (ATAK validates) β
β Stale time β Must β¦ β Extended automatically for routes/shapes β
β Offline queue β β€ 50 β¦ β Oldest evicted on overflow; expired purged on drain β
β Port 8089 binding β Must β¦ β Server start returns T383838Result.failure with user-visible error β
βββββββββββββββββββββββββββββ΄βββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Wire Format
TAKPacketV2 (Port 78)
T282828
βββββββββββ¬βββββββββββββββββββββββββββββββββ
β Flags β Compressed TAKPacketV2 Protobuf β
β (1 byte)β (variable, β€224 bytes) β
βββββββββββ΄βββββββββββββββββββββββββββββββββ
Flags byte:
Bits 0-5: Dictionary ID (0=non-aircraft, 1=aircraft)
Bits 6-7: Reserved
0xFF: Uncompressed (raw protobuf follows)
TAKPacket (Port 72, Legacy)
T282828
ββββββββββββββββββββββββββββββββ
β Raw TAKPacket Protobuf β
β (no compression, no header) β
ββββββββββββββββββββββββββββββββ
Key Constants
T282828
Tff7b72const Tff7b72val Te6edf3DEFAULT_TAK_PORT Tff7b72= T79c0ff8T79c0ff0T79c0ff8T79c0ff9
Tff7b72const Tff7b72val Te6edf3MAX_TAK_WIRE_PAYLOAD_BYTES Tff7b72= T79c0ff2T79c0ff2T79c0ff5
Tff7b72const Tff7b72val Te6edf3MAX_DECOMPRESSED_SIZE Tff7b72= T79c0ff4T79c0ff0T79c0ff9T79c0ff6
Tff7b72const Tff7b72val Te6edf3TAK_COORDINATE_SCALE Tff7b72= T79c0ff1Te6edf3e7 T8b949e// lat/lon β int scaling
Tff7b72const Tff7b72val Te6edf3DICT_ID_NON_AIRCRAFT Tff7b72= T79c0ff0
Tff7b72const Tff7b72val Te6edf3DICT_ID_AIRCRAFT Tff7b72= T79c0ff1
Tff7b72const Tff7b72val Te6edf3DICT_ID_UNCOMPRESSED Tff7b72= T79c0ff0Te6edf3xFF
Tff7b72val Te6edf3OFFLINE_QUEUE_TTL Tff7b72= T79c0ff5.Te6edf3minutes
Tff7b72const Tff7b72val Te6edf3OFFLINE_QUEUE_MAX_SIZE Tff7b72= T79c0ff5T79c0ff0
Tff7b72val Te6edf3KEEPALIVE_INTERVAL Tff7b72= T79c0ff1T79c0ff0.Te6edf3seconds
Tff7b72val Te6edf3MIN_MESH_STALE_TTL Tff7b72= T79c0ff1T79c0ff5.Te6edf3minutes
Served by rngit 1.5.0 - Generated in 0.07s